Summary

%NimbleOptions.ValidationError{}.key is typed atom() but the struct already stores a list of atoms for the "unknown options" case. This PR widens the type to match runtime behavior.

Evidence

• The "unknown options" error path passes a list of keys at lib/nimble_options.ex:524:

  keys ->
    error_tuple(
      keys,
      nil,
      "unknown options #{inspect(keys)}, valid options are: #{inspect(valid_opts)}"
    )

• test "unknown options" asserts the list form:

  key: [:not_an_option1, :not_an_option2]

• Runtime behavior is intentional. The typespec was misleading.

Why this matters

The set-theoretic type checker introduced in elixir-lang/elixir#15366 reads @type t :: %__MODULE__{key: atom()} literally. Every call site that passes a list where atom() is declared fires a warning. nimble_options is depended on by several top Hex packages (finch, oban, req, swoosh, tesla, ex_aws, phoenix_live_view), so this single mismatch cascades into downstream warnings for their consumers.

Widening the type matches what the code already does. No code change, no test change.

Change

-          key: atom(),
+          key: atom() | [atom()],

Plus a doc update on the :key field calling out the multi-key case.

Verification

mix test: 156/156 pass. mix compile clean under the new checker.